Time Base Callback Functions2

If your application uses QuickTime time bases, it may define callback functions that are associated with a specific time base. Your application can then use these callback functions to perform activities that are triggered by temporal events, such as a certain time being reached or a specified rate being achieved. The time base functions of the Movie Toolbox interact with clock components to schedule the invocation of these callback functions--clock components are responsible for invoking the callback function at its scheduled time. Your application can use the functions described in this section to establish your own callback function and to schedule callback events.

You can define three types of callback events. These types are distinguished by the nature of the temporal event that triggers the Movie Toolbox to call your function. The three types are

You specify a callback event's type when you define the callback event, using the NewCallBack function.

You specify whether your event can occur at interrupt time when you define the callback event, using the NewCallBack function. Your function is called closer to the triggering event at interrupt time, but it is subject to all the restrictions of interrupt functions (for example, your callback function cannot cause memory to be moved). If your function is not called at interrupt time, you are free of these restrictions--but your function may be called later, because the invocation is delayed to avoid interrupt time.

The NewCallBack function allocates the memory to support a callback event. When you are done with the callback event, you dispose of it by calling the DisposeCallBack function.

You schedule a callback event by calling the CallMeWhen function. Call CancelCallBack function to unschedule a callback event.

You can retrieve the time base of a callback event by calling the GetCallBackTimeBase function. You can obtain the type of a callback event by calling the GetCallBackType function.

NewCallBack

The NewCallback function creates a new callback event. The callback event created at this time is not active until you schedule it by calling the CallMeWhen function, which is described in the next section.

You must not call this function at interrupt time.



 
pascal QTCallBack NewCallBack (TimeBase tb, short cbType);

tb: Specifies the callback event's time base. You obtain this identifier from the NewTimeBase function (described on NewTimeBase ).
cbType: Specifies when the callback event is to be invoked. The value of this field governs how the Movie Toolbox interprets the data supplied in the param1 , param2 , and param3 parameters to the CallMeWhen function, which is described in the next section. The following values are valid for this parameter:; In addition, if the high-order bit of the cbType parameter is set to 1 (this bit is defined by the callBackAtInterrupt flag), the event can be invoked at interrupt time.

DESCRIPTION

The NewCallBack function returns a reference to the new callback event. You must provide this reference to other Movie Toolbox functions described in this section. If the Movie Toolbox cannot create the callback event, this function returns nil .

ERROR CODES

None

CallMeWhen

You schedule a callback event by calling the CallMeWhen function. You can call this function from your callback function.



 
pascal OSErr CallMeWhen (QTCallBack cb, 

                                         QTCallBackUPP callBackProc, 

                                         long refcon, long param1, 

                                         long param2, long param3);

cb: Specifies the callback event for the operation. You obtain this identifier from the NewCallBack function, which is described in the previous section.
callBackProc: Points to your callback function.; Your callback function must have the following form:



 
                    pascal void MyCallBackProc (QTCallBack cb, 

                                         long refcon);

See "Callback Event Functions" for details.
refcon: Contains a reference constant value for your callback function.
param1: Contains scheduling information. The Movie Toolbox interprets this parameter based on the value of the cbType parameter to the NewCallBack function, described in the previous section.; If cbType is set to callBackAtTime , the param1 parameter contains flags indicating when to invoke your callback function for this callback event. The following values are defined (be sure to set unused flags to 0):; If the cbType parameter is set to callBackAtRate , param1 contains flags indicating when to invoke your callback function for this event. The following values are defined (be sure to set unused flags to 0):
param2: Contains scheduling information. The Movie Toolbox interprets this parameter based on the value of the cbType parameter to the NewCallBack function, described in the previous section.; If cbType is set to callBackAtTime , the param2 parameter contains the time value at which your callback function is to be invoked for this event. The param1 parameter contains flags affecting when the Movie Toolbox calls your function.; If cbType is set to callBackAtRate , the param2 parameter contains the rate value at which your callback function is to be invoked for this event. The param1 parameter contains flags affecting when the Movie Toolbox calls your function.
param3: Contains the time scale in which to interpret the time value that is stored in param3 if cbType is set to callBackAtTime .

ERROR CODES

None

CancelCallBack

You use the CancelCallBack function to cancel a callback event before it executes.



 
pascal void CancelCallBack (QTCallBack cb);

cb: Specifies the callback event for this operation. You obtain this value from the NewCallBack function (described on NewCallBack ).

DESCRIPTION

The CancelCallBack function removes the callback event from the list of callback events maintained by the Movie Toolbox. The Movie Toolbox calls this function automatically when it invokes your callback function. In order for a callback event to be scheduled, you must call the CallMeWhen function, which is described in the previous section.

ERROR CODES

None

GetCallBackType

You can retrieve a callback event's type by calling the GetCallBackType function. You specify the type value when you call the NewCallBack function (described on NewCallBack ).



 
pascal short GetCallBackType (QTCallBack cb);

cb: Specifies the callback event for the operation. You obtain this value from the NewCallBack function.

DESCRIPTION

The GetCallBackTimeBase function returns the callback event's type value. The following values are valid:

callBackAtTime: Indicates that the event is to be invoked at a specified time.
callBackAtRate: Indicates that the event is to be invoked when the rate for the time base reaches a specified value.
callBackAtTimeJump: Indicates that the event is to be invoked when the time base's time value changes by an amount that differs from its rate.

In addition, if the high-order bit of the returned value is set to 1 (this bit is defined by the callBackAtInterrupt flag), the event can be invoked at interrupt time.

ERROR CODES

None